/*
  *         *
         * Copyright  1990-2007 Sun Microsystems, Inc. All Rights Reserved.
         * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
         *
007:         * This program is free software; you can redistribute it and/or
008:         * modify it under the terms of the GNU General Public License version
009:         * 2 only, as published by the Free Software Foundation.
010:         *
011:         * This program is distributed in the hope that it will be useful, but
012:         * WITHOUT ANY WARRANTY; without even the implied warranty of
013:         * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014:         * General Public License version 2 for more details (a copy is
015:         * included at /legal/license.txt).
016:         *
017:         * You should have received a copy of the GNU General Public License
018:         * version 2 along with this work; if not, write to the Free Software
019:         * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020:         * 02110-1301 USA
021:         *
022:         * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023:         * Clara, CA 95054 or visit www.sun.com if you need additional
024:         * information or have any questions.
025:         */

        package javax.microedition.io;

        import java.lang.IllegalArgumentException;
        import java.io.IOException;
        import java.lang.String;

        /**
034:         * This interface defines the socket stream connection.
035:         * <P>
036:         * A socket is accessed using a generic connection string with an explicit host
037:         * and port number. The host may be specified as a fully qualified host name or
038:         * IPv4 number.
039:         * e.g. <code>socket://host.com:79</code> defines a target socket on the
040:         * <code>host.com</code> system at
041:         * port <code>79</code>.
042:         * <P>Note that
043:         * RFC1900 recommends the use of names rather than IP numbers for best results
044:         * in the event of IP number reassignment. </P>
045:         * <H3> Closing Streams </H3>
046:         * <P>
047:         * Every <code>StreamConnection</code> provides a <code>Connection</code>
048:         * object as well as an <code>InputStream</code> and <code>OutputStream</code>
049:         * to handle the I/O associated with the connection. Each of these interfaces
050:         * has its own <code>close()</code> method. For systems that support
051:         * duplex communication over the socket connection, closing of the
052:         * input or output stream SHOULD shutdown just that side of the
053:         * connection. e.g. closing the <code>InputStream</code> will permit the
054:         * <code>OutputStream</code> to continue sending data.
055:         * </P>
056:         * <P>
057:         * Once the input or output stream has been closed, it can only be reopened
058:         * with a call to <code>Connector.open()</code>. The application will receive
059:         * an <code>IOException</code> if an attempt is made to reopen the stream.
060:         * </P>
061:         * <H2>
062:         * BNF Format for Connector.open() string
063:         * </H2>
064:         * <P>
065:         * The URI must conform to the BNF syntax specified below.  If the URI
066:         * does not conform to this syntax, an <code>IllegalArgumentException</code>
067:         * is thrown.
068:         * </P>
069:         * <TABLE BORDER="1">
070:         * <TR>
071:         * <TD>&lt;socket_connection_string&gt; </TD>
072:         * <TD>::= "<strong>socket://</strong>"&lt;hostport&gt; </TD>
073:         * </TR>
074:         * <TR>
075:         * <TD>&lt;hostport&gt; </TD>
076:         * <TD>::= <I>host</I> ":" <I>port </I> </TD>
077:         * </TR>
078:         * <TR>
079:         * <TD>&lt;host&gt; </TD>
080:         * <TD>::= <I>host name or IP address </I> (omitted for inbound connections,
081:         * See <a href="ServerSocketConnection.html">ServerSocketConnection</a>)
082:         * </TD>
083:         * </TR>
084:         * <TR>
085:         * <TD>&lt;port&gt; </TD>
086:         * <TD>::= <I>numeric port number </I> </TD>
087:         * </TR>
088:         * </TABLE>
089:         * <H3>
090:         * Examples
091:         * </H3>
092:         * <P>
093:         * The following examples show how a <code>SocketConnection</code>
094:         * would be used to access a sample loopback program.
095:         * </P>
096:         * <PRE>
097:         *   SocketConnection sc = (SocketConnection)
098:         *                         Connector.open("socket://host.com:79");
099:         *   sc.setSocketOption(SocketConnection.LINGER, 5);
100:         *
101:         *   InputStream is  = sc.openInputStream();
102:         *   OutputStream os = sc.openOutputStream();
103:         *
104:         *   os.write("\r\n".getBytes());
105:         *   int ch = 0;
106:         *   while(ch != -1) {
107:         *       ch = is.read();
108:         *   }
109:         *
110:         *   is.close();
111:         *   os.close();
112:         *   sc.close();
113:         * </PRE>
114:         */
       public interface SocketConnection extends StreamConnection {

           /**
118:             * Socket option for the small buffer <em>writing delay</em> (0).
119:             * Set to zero to disable Nagle algorithm for
120:             * small buffer operations.
121:             * Set to a non-zero value to enable.
122:             */
            public final byte DELAY = 0;

         /**
126:             * Socket option for the <em>linger time</em> to wait in seconds
127:             * before closing a connection with
128:             * pending data output (1). Setting the linger time to zero
129:             * disables the linger wait interval.
130:             */
            public final byte LINGER = 1;

            /**
134:             * Socket option for the <em>keep alive</em> feature (2).
135:             * Setting KEEPALIVE to zero will disable the feature.
136:             * Setting KEEPALIVE to a non-zero value will enable the feature.
137:             */
            public final byte KEEPALIVE = 2;

            /**
141:             * Socket option for the size of the <em>receiving buffer</em> (3).
142:             */
           public final byte RCVBUF = 3;

           /**
146:             * Socket option for the size of the <em>sending buffer</em> (4).
147:             */
         public final byte SNDBUF = 4;

           /**
151:             * Set a socket option for the connection.
152:             * <P>
153:             * Options inform the low level networking code about intended
154:             * usage patterns that the application will use in dealing with
155:             * the socket connection.
156:             * </P>
157:             * <P>
158:             * Calling <code>setSocketOption</code> to assign buffer sizes
159:             * is a hint to the platform of the sizes to set the underlying
160:             * network I/O buffers.
161:             * Calling <code>getSocketOption</code> can  be used to see what
162:             * sizes the system is using.
163:             * The system MAY adjust the buffer sizes to account for
164:             * better throughput available from Maximum Transmission Unit
165:             * (MTU) and Maximum Segment Size (MSS) data available
166:             * from current network information.
167:             * </P>
168:             *
169:             * @param option socket option identifier (KEEPALIVE, LINGER,
170:             * SNDBUF, RCVBUF, or DELAY)
171:             * @param value numeric value for specified option
172:             * @exception  IllegalArgumentException if  the value is not
173:             *              valid (e.g. negative value) or if the option
174:             *              identifier is not valid
175:             * @exception  IOException  if the connection was closed
176:             *
177:             * @see #getSocketOption
178:             */
           public void setSocketOption(byte option, int value)
                   throws IllegalArgumentException, IOException;

          /**
183:             * Get a socket option for the connection.
184:             *
185:             * @param option socket option identifier (KEEPALIVE, LINGER,
186:             * SNDBUF, RCVBUF, or DELAY)
187:             * @return  numeric value for specified option or -1 if the
188:             *  value is not available.
189:             * @exception IllegalArgumentException if the option identifier is
190:             *  not valid
191:             * @exception  IOException  if the connection was closed
192:             * @see #setSocketOption
193:             */
          public int getSocketOption(byte option)
                   throws IllegalArgumentException, IOException;

            /**
198:             * Gets the local address to which the socket is bound.
199:             *
200:             * <P>The host address(IP number) that can be used to connect to this
201:             * end of the socket connection from an external system.
202:             * Since IP addresses may be dynamically assigned, a remote application
203:             * will need to be robust in the face of IP number reassignment.</P>
204:             * <P> The local hostname (if available) can be accessed from
205:             * <code> System.getProperty("microedition.hostname")</code>
206:             * </P>
207:             *
208:             * @return the local address to which the socket is bound.
209:             * @exception  IOException  if the connection was closed.
210:             * @see ServerSocketConnection
211:             */
          public String getLocalAddress() throws IOException;

           /**
215:             * Returns the local port to which this socket is bound.
216:             *
217:             * @return the local port number to which this socket is connected.
218:             * @exception  IOException  if the connection was closed.
219:             * @see ServerSocketConnection
220:             */
          public int getLocalPort() throws IOException;

            /**
224:             * Gets the remote address to which the socket is bound.
225:             * The address can be either the remote host name or the IP
226:             * address(if available).
227:             *
228:             * @return the remote address to which the socket is bound.
229:             * @exception  IOException  if the connection was closed.
230:             */
           public String getAddress() throws IOException;

           /**
234:             * Returns the remote port to which this socket is bound.
235:             *
236:             * @return the remote port number to which this socket is connected.
237:             * @exception  IOException  if the connection was closed.
238:             */
          public int getPort() throws IOException;
       }